API Overview
This document provides a comprehensive API overview for the FastAPI server. It explains the overall architecture, endpoint organization, routing structure, and how base URL patterns map to distinct service areas. It also covers application initialization, startup modes, logging configuration, and error handling strategies. Authentication mechanisms are documented in terms of access tokens passed via request bodies, and CORS configuration is noted as not being explicitly configured in the provided code. Health checks and monitoring interfaces are described, along with practical usage patterns and integration scenarios.
The API server is organized around a FastAPI application that aggregates multiple routers under distinct base prefixes. Each router corresponds to a functional area (e.g., GenAI, Google Search, Gmail, Calendar, PyJiit, React Agent, Website, Validator, Upload). The application can be started either as the API server or as an MCP server via a top-level entry point.
Entry point"] --> B_api_run["api/run.py
run(host,port,reload)"] B_api_run --> C_api_main["api/main.py
FastAPI app + router mounts"] C_api_main --> D_routers["routers/*
Feature-specific routers"] D_routers --> E_health["/api/genai/health"] D_routers --> F_genai_github["/api/genai/github"] D_routers --> G_genai_website["/api/genai/website"] D_routers --> H_genai_youtube["/api/genai/youtube"] D_routers --> I_google_search["/api/google-search"] D_routers --> J_gmail["/api/gmail"] D_routers --> K_calendar["/api/calendar"] D_routers --> L_pyjiit["/api/pyjiit"] D_routers --> M_genai_react["/api/genai/react"] D_routers --> N_validator["/api/validator"] D_routers --> O_agent["/api/agent"] D_routers --> P_upload["/api/upload"]
Diagram sources
Section sources
Application factory and router mounts: The FastAPI app is created and routers are included under base prefixes to segment functionality by domain.
Startup orchestration: A top-level script chooses between running the API server or the MCP server, delegating to the API runner.
Configuration and logging: Environment variables drive runtime behavior and logging level; a shared logger getter is used across modules.
Health endpoint: A dedicated router exposes a simple health check returning a structured response model.
Key implementation references:
Application creation and router mounts: api/main.py
Startup selection and API runner: main.py, api/run.py
Configuration and logging: core/config.py, core/config.py
Health response model: models/response/health.py
Health handler: routers/health.py
Section sources
The API follows a modular FastAPI architecture:
Central app definition and router composition
Feature-based routers grouped under base prefixes
Request validation via Pydantic models
Service-layer delegation per router
Global exception handling returning standardized HTTP errors
Optional root endpoint returning app metadata
Diagram sources
Endpoint Organization and Base URL Patterns#
Routers are mounted under the following base prefixes to separate service domains:
GenAI family: /api/genai/health, /api/genai/github, /api/genai/website, /api/genai/youtube, /api/genai/react
Google family: /api/google-search
Productivity: /api/gmail, /api/calendar, /api/pyjiit
Validation and utilities: /api/validator, /api/agent, /api/upload
These mounts are defined in the central app file and exported via the routers package.
Section sources
Health Check Endpoint#
Path: GET /api/genai/health
Handler: Returns a structured response indicating service health
Response model: HealthResponse with status and message fields
Diagram sources
Section sources
Website Answer Endpoint#
Path: POST /api/genai/website
Request model: WebsiteRequest (validated in router)
Service: WebsiteService injected via dependency
Behavior: Validates presence of URL and question; delegates to service; returns answer in a dictionary
Error handling: Raises HTTP 400 for missing fields; wraps unexpected errors as HTTP 500
Diagram sources
Section sources
Google Search Endpoint#
Path: POST /api/google-search
Request model: SearchRequest with query and optional max_results
Service: GoogleSearchService injected via dependency
Behavior: Validates query; calls service.search; returns results in a dictionary
Error handling: Raises HTTP 400 for invalid input; wraps unexpected errors as HTTP 500
Diagram sources
Section sources
Gmail Endpoints#
Paths:
POST /api/gmail/unread
POST /api/gmail/latest
POST /api/gmail/mark_read
POST /api/gmail/send
Request models: UnreadRequest, LatestRequest, MarkReadRequest, SendEmailRequest (all require access_token)
Service: GmailService injected via dependency
Behavior: Validates required fields; calls appropriate service methods; returns structured results
Error handling: Raises HTTP 400 for missing fields; wraps unexpected errors as HTTP 500
Diagram sources
Section sources
Calendar Endpoints#
Paths:
POST /api/calendar/events
POST /api/calendar/create
Request models: EventsRequest (requires access_token), CreateEventRequest (requires access_token, summary, start_time, end_time)
Service: CalendarService injected via dependency
Behavior: Validates required fields and ISO 8601 timestamps; calls service methods; returns structured results
Error handling: Raises HTTP 400 for invalid input; wraps unexpected errors as HTTP 500
Diagram sources
Section sources
React Agent Endpoint#
Path: POST /api/genai/react
Request model: CrawlerRequest (validated in router)
Service: ReactAgentService injected via dependency
Behavior: Validates question; delegates to service.generate_answer; returns CrawllerResponse
Error handling: Raises HTTP 400 for missing question; wraps unexpected errors as HTTP 500
Diagram sources
Section sources
Application Initialization, Middleware, and Global Settings#
Application creation: FastAPI app is instantiated with title and version.
Router mounts: Routers are imported from the routers package and mounted under base prefixes.
Root endpoint: Optional GET “/” returns app metadata.
No explicit middleware or CORS configuration is present in the provided code.
Logging: Centralized logger getter is used across modules; environment variables control debug level and backend host/port.
Section sources
Authentication Mechanisms#
Access tokens are passed via request bodies for sensitive operations:
Gmail: access_token required for all endpoints
Calendar: access_token required for all endpoints
Website: no token required in the endpoint shown
Google Search: no token required in the endpoint shown
The code does not implement bearer token middleware or route guards; token validation occurs inside each endpoint’s request model and service invocation.
Section sources
CORS Configuration#
No explicit CORS configuration is present in the provided code. If cross-origin requests are needed, configure CORS in the FastAPI app before including routers.
[No sources needed since this section provides general guidance]
Error Handling Strategies#
Centralized try/catch blocks in each endpoint:
Raise HTTP 400 for invalid input (missing fields, malformed data)
Wrap unexpected exceptions as HTTP 500 with sanitized details
Services log exceptions internally; endpoints re-raise as HTTP exceptions to maintain consistent error responses.
Section sources
Monitoring Interfaces#
Health endpoint: GET /api/genai/health provides a simple readiness/liveness indicator.
Logging: Centralized logger is used across modules; environment controls verbosity.
Section sources
Basic API Usage Patterns and Integration Scenarios#
Start the API server:
Run the top-level script and choose API mode, or pass the --api flag.
The API listens on host and port configured via environment variables.
Example flows:
Website QA: POST to /api/genai/website with a URL and question; receive an answer.
Google Search: POST to /api/google-search with a query and optional max_results; receive results.
Gmail operations: Use access_token in request bodies to list unread messages, fetch latest messages, mark read, or send emails.
Calendar operations: Use access_token to list events or create events with ISO 8601 start/end times.
Health check: GET /api/genai/health to verify service availability.
Section sources
The API module composes routers and services with clear separation of concerns. Routers depend on service classes, which encapsulate tool integrations. The central app depends on the routers package for imports and mounts.
Diagram sources
Section sources
Keep request payloads minimal; avoid unnecessary fields to reduce parsing overhead.
Validate inputs early in routers to fail fast and reduce downstream processing.
Reuse injected services per request to minimize initialization costs.
Monitor logs and adjust logging level via environment variables for production deployments.
[No sources needed since this section provides general guidance]
Health check failures:
Verify GET /api/genai/health returns the expected status and message.
400 Bad Request errors:
Ensure required fields are present (e.g., query, access_token, question).
500 Internal Server Errors:
Inspect logs for exception traces; services already log exceptions internally.
Startup issues:
Confirm environment variables for host/port and debug level are set appropriately.
Use the top-level script to select API mode and run the server.
Section sources
The FastAPI server organizes functionality into clearly separated routers under distinct base prefixes, enabling modular development and clear ownership of features. The application initializes cleanly, exposes a health endpoint, and handles errors consistently. Authentication is token-based and validated at the router level. While CORS and middleware are not configured in the provided code, the architecture supports easy addition of such features. The documented endpoints and usage patterns provide a solid foundation for integrating clients and extending functionality.
Startup command and mode selection are handled by the top-level script, which delegates to the API runner.
Section sources